docs: managing projects #2696
docs: managing projects #2696
Conversation
✅ Deploy Preview for docs-kargo-io ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ Deploy Preview for docs-kargo-akuity-io ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2696 +/- ##
=======================================
Coverage 50.02% 50.02%
=======================================
Files 275 275
Lines 24559 24559
=======================================
Hits 12285 12285
Misses 11603 11603
Partials 671 671 ☔ View full report in Codecov by Sentry. |
| @@ -4,3 +4,39 @@ sidebar_label: Managing Projects | |||
| --- | |||
|
|
|||
| # Managing Projects | |||
|
|
|||
There was a problem hiding this comment.
I think this page really needs lead off with some brief overview of what a Project is exactly. Rather than re-create sections of the concepts doc, I think parts of that doc should move here. But that also means we're going to need to create "Working with Stages," "Working with Warehouses," etc. and move applicable chunks of the concepts doc over to those.
This would leave us in a spot where the concepts doc would probably keep the holistic, but very high level overview of Kargo and lose all the sections that dive into the actual CRDs. Each concept could be linked, at the end, to the corresponding "Working with ____" doc.
This would also advance us quite a bit farther toward the goal of (eventually) re-organizing the entire doc tree into "bite size" operator topics and user topics.
All of this being said... I don't want to see the scope of this PR creep to include all of the above, so for now let's add a very brief overview here in this section. I think it should go as far as describing the way things typically work -- create a Project, the corresponding namespace is automatically created along with other boilerplate initialization. You can lift bits out of the concepts doc to flesh this out.
Then the section below needs only to cover the "adoption" case.
There was a problem hiding this comment.
How about we call this document as "Working with Projects" instead of "Managing Projects"
That way we have a streamlined doc tree with:
- Overview
- Key Concepts
- Quickstart
- How to Guides
- Installing Kargo
- Managing User Permissions
- Managing Credentials
- Working with Projects
- Working with Stage
- Working with Freight
- Working with Warehouse
- Working with Promotion
There was a problem hiding this comment.
Yes. "Working with ____" would be my preference.
| @@ -4,3 +4,39 @@ sidebar_label: Managing Projects | |||
| --- | |||
|
|
|||
| # Managing Projects | |||
|
|
|||
| ### Namespace Creation and Adoption in Kargo Projects | |||
There was a problem hiding this comment.
| ### Namespace Creation and Adoption in Kargo Projects | |
| ## Namespace Adoption |
| When a new Kargo `Project` is created, it automatically generates a corresponding Kubernetes `namespace`. | ||
| In scenarios where specific configuration requirements are needed, Kargo offers an adoption feature for | ||
| pre-existing namespaces. |
There was a problem hiding this comment.
Example of what I was talking about here.
This first sentence can move up to the previous section. The second is adoption-specific and ought to remain.
| Kargo can adopt namespaces that you create beforehand, if they are labeled | ||
| with `kargo.akuity.io/project: "true"`. |
There was a problem hiding this comment.
This feels a little repetitious. The previous paragraph basically said the same thing, but with less detail. Maybe kill the previous one and keep this one.
| and resources. Ensure the label `kargo.akuity.io/project: "true"` is applied to the `namespace`. | ||
| * When using a YAML file, list the `namespace` definition above the Kargo `Project` resource to ensure it is created first. | ||
|
|
||
| In the following example, the `namespace` is labeled with `eso.example.com.au: cluster-secret-store-alpha` previously. |
There was a problem hiding this comment.
What is eso.example.com.au? I think we should try to make the example really generic. Something like labeling the namespace with the org that owns it. Introduce the example by saying (something like), "If your policy agent enforces a policy that all namespaces must be labeled with the internal org that is responsible for it..."
| and statistics in `Project` resources. | ||
| ::: | ||
|
|
||
| ### Promotion Policies |
There was a problem hiding this comment.
Please review the ### heading.
|
|
||
| # Managing Projects | ||
|
|
||
| Each Kargo project is represented by a cluster-scoped Kubernetes resource of |
There was a problem hiding this comment.
This section is transferred from the Key-Concepts CRD docs.
Signed-off-by: Faeka Ansari <[email protected]>
Signed-off-by: Faeka Ansari <[email protected]>
Signed-off-by: Faeka Ansari <[email protected]>
Signed-off-by: Faeka Ansari <[email protected]>
fykaa
force-pushed
the
managing-projects
branch
from
c9898a6
to
d3be0ce
Compare
docs/docs/15-concepts.md
Outdated
| For more information on the Project Resource types, promotion policies, | ||
| and namespace adoption refer to [Managing Projects](./30-how-to-guides/40-managing-projects.md) in the How-to guides. |
There was a problem hiding this comment.
| For more information on the Project Resource types, promotion policies, | |
| and namespace adoption refer to [Managing Projects](./30-how-to-guides/40-managing-projects.md) in the How-to guides. | |
| For technical information on the corresponding `Project` resource type, refer to [Working with Projects](./30-how-to-guides/11-working-with-projects.md). |
| :::info | ||
| In future releases, the team also expects to also aggregate project-level status | ||
| and statistics in `Project` resources. | ||
| ::: |
There was a problem hiding this comment.
This was our intention at one point, but everything that's been done to date for collecting metrics actually isn't tied (not directly at least) into the Project type. It doesn't mean we won't head in this direction, but being less certain, let's kill off this info box.
| and statistics in `Project` resources. | ||
| ::: | ||
|
|
||
| ### Promotion Policies |
There was a problem hiding this comment.
| ### Promotion Policies | |
| ## Promotion Policies |
| To ensure compliance with governance policies, you may need | ||
| to pre-configure namespaces with specific labels or annotations | ||
| required by your organization's policy agents. | ||
|
|
||
| Kargo supports the adoption of pre-existing namespaces that are | ||
| labeled with `kargo.akuity.io/project: "true"`. This enables you | ||
| to pre-configure namespaces according to your organization's requirements. |
There was a problem hiding this comment.
| To ensure compliance with governance policies, you may need | |
| to pre-configure namespaces with specific labels or annotations | |
| required by your organization's policy agents. | |
| Kargo supports the adoption of pre-existing namespaces that are | |
| labeled with `kargo.akuity.io/project: "true"`. This enables you | |
| to pre-configure namespaces according to your organization's requirements. | |
| At times, `Namespace`s may require specific configuration to | |
| comply with regulatory or organizational requirements. To | |
| account for this, Kargo supports the adoption of pre-existing | |
| `Namespace`s that are labeled with `kargo.akuity.io/project: "true"`. | |
| This enables you pre-configure such `Namespace`s according to your | |
| own requirements. |
There was a problem hiding this comment.
I would add an info box after this section to elaborate that the purpose of the kargo.akuity.io/project: "true" label is to prevent Kargo users from hijacking existing non-Project namespaces.
| For example, if your policy agent mandates that all namespaces include | ||
| a label identifying the internal organization responsible for them, | ||
| you can define the `namespace` in your YAML manifest with | ||
| the necessary labels and resources: | ||
|
|
||
| * Add the label `kargo.akuity.io/project: "true"` to your `namespace` definition. | ||
| * Ensure that in your YAML file, the `namespace` definition is listed above the | ||
| Kargo `Project` resource to allow it to be created first. | ||
|
|
||
| In this example, the `namespace` is pre-labeled to indicate the responsible | ||
| internal organization. When the Kargo `Project` is created, it automatically | ||
| adopts this pre-existing `namespace`. |
There was a problem hiding this comment.
| For example, if your policy agent mandates that all namespaces include | |
| a label identifying the internal organization responsible for them, | |
| you can define the `namespace` in your YAML manifest with | |
| the necessary labels and resources: | |
| * Add the label `kargo.akuity.io/project: "true"` to your `namespace` definition. | |
| * Ensure that in your YAML file, the `namespace` definition is listed above the | |
| Kargo `Project` resource to allow it to be created first. | |
| In this example, the `namespace` is pre-labeled to indicate the responsible | |
| internal organization. When the Kargo `Project` is created, it automatically | |
| adopts this pre-existing `namespace`. | |
| For example, if your policy agent mandates that all `Namespace`s include | |
| a label identifying the internal organization responsible for them, you | |
| can define such a `Namespace` directly as in the following example: |
| metadata: | ||
| name: kargo-example | ||
| spec: | ||
| # Project specifications go here |
There was a problem hiding this comment.
| # Project specifications go here | |
| # Project specifications go here |
There was a problem hiding this comment.
You might want to double-check how many spaces are used per level of indentation in YAML examples throughout the rest of the docs. This looks like more than we've used in other places, but it may be my imagination.
There was a problem hiding this comment.
I pressed tab key, it adds 4 spaces always
| # Project specifications go here | ||
| ``` | ||
|
|
||
| This setup allows the Kargo `Project` to recognize and utilize your pre-configured `namespace` seamlessly, aligning with your compliance requirements without additional updates. |
There was a problem hiding this comment.
I think we've gotten our point across without saying this. Remember there's an art to getting your point across without overwhelming the reader with more words than necessary.
|
This looks great. All my remaining feedback are minor tweaks that are easy fixes. |
Signed-off-by: Faeka Ansari <[email protected]>
minor tweaks Signed-off-by: Kent Rancourt <[email protected]>
Signed-off-by: Kent Rancourt <[email protected]>
Signed-off-by: Kent Rancourt <[email protected]>
Signed-off-by: Faeka Ansari <[email protected]> Signed-off-by: Kent Rancourt <[email protected]> Co-authored-by: Kent Rancourt <[email protected]> (cherry picked from commit dbac911)
|
Successfully created backport PR for |
closes: #2528